home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / ucal.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  24KB  |  677 lines
  1. /*
  2. *******************************************************************************
  3. *                                                                             *
  4. * COPYRIGHT:                                                                  *
  5. *   (C) Copyright Taligent, Inc.,  1996                                       *
  6. *   (C) Copyright International Business Machines Corporation,  1998-1999     *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.        *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure   *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                    *
  10. *                                                                             *
  11. *******************************************************************************
  12. */
  13.  
  14. #ifndef UCAL_H
  15. #define UCAL_H
  16.  
  17. #include "utypes.h"
  18. /**
  19.  * UCalendar C API is used  for converting between a <code>UDate</code> object
  20.  * and a set of integer fields such as <code>UCAL_YEAR</code>, <code>UCAL_MONTH</code>, 
  21.  * <code>UCAL_DAY</code>, <code>UCAL_HOUR</code>, and so on.
  22.  * (A <code>UDate</code> object represents a specific instant in
  23.  * time with millisecond precision. See
  24.  * {@link UDate}
  25.  * for information about the <code>UDate</code> .)
  26.  *
  27.  * <p>
  28.  * Types of <code>UCalendar</code> interpret a <code>UDate</code>
  29.  * according to the rules of a specific calendar system. The U_CAPI
  30.  * provides the enum UCalendarType with UCAL_TRADITIONAL and 
  31.  * UCAL_GREGORIAN.
  32.  * <p>
  33.  * Like other locale-sensitive C API, calendar API  provides a
  34.  * function, <code>ucal_open()</code>, which returns a pointer to
  35.  * <code>UCalendar</code> whose time fields have been initialized 
  36.  * with the current date and time. We need to specify the type of
  37.  * calendar to be opened and the  timezoneId. 
  38.  * <blockquote>
  39.  * <pre>
  40.  * UCalendar *caldef;
  41.  * UChar *tzId;
  42.  * UErrorCode status;
  43.  * tzId=(UChar*)malloc(sizeof(UChar) * (strlen("PST") +1) );
  44.  * u_uastrcpy(tzId, "PST");
  45.  * caldef=ucal_open(tzID, u_strlen(tzID), NULL, UCAL_TRADITIONAL, &status);
  46.  * </pre>
  47.  * </blockquote>
  48.  *
  49.  * <p>
  50.  * A <code>UCalendar</code> object can produce all the time field values
  51.  * needed to implement the date-time formatting for a particular language
  52.  * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
  53.  *
  54.  * <p>
  55.  * When computing a <code>UDate</code> from time fields, two special circumstances
  56.  * may arise: there may be insufficient information to compute the
  57.  * <code>UDate</code> (such as only year and month but no day in the month),
  58.  * or there may be inconsistent information (such as "Tuesday, July 15, 1996"
  59.  * -- July 15, 1996 is actually a Monday).
  60.  *
  61.  * <p>
  62.  * <strong>Insufficient information.</strong> The calendar will use default
  63.  * information to specify the missing fields. This may vary by calendar; for
  64.  * the Gregorian calendar, the default for a field is the same as that of the
  65.  * start of the epoch: i.e., UCAL_YEAR = 1970, UCAL_MONTH = JANUARY, UCAL_DATE = 1, etc.
  66.  *
  67.  * <p>
  68.  * <strong>Inconsistent information.</strong> If fields conflict, the calendar
  69.  * will give preference to fields set more recently. For example, when
  70.  * determining the day, the calendar will look for one of the following
  71.  * combinations of fields.  The most recent combination, as determined by the
  72.  * most recently set single field, will be used.
  73.  *
  74.  * <blockquote>
  75.  * <pre>
  76.  * UCAL_MONTH + UCAL_DAY_OF_MONTH
  77.  * UCAL_MONTH + UCAL_WEEK_OF_MONTH + UCAL_DAY_OF_WEEK
  78.  * UCAL_MONTH + UCAL_DAY_OF_WEEK_IN_MONTH + UCAL_DAY_OF_WEEK
  79.  * UCAL_DAY_OF_YEAR
  80.  * UCAL_DAY_OF_WEEK + UCAL_WEEK_OF_YEAR
  81.  * </pre>
  82.  * </blockquote>
  83.  *
  84.  * For the time of day:
  85.  *
  86.  * <blockquote>
  87.  * <pre>
  88.  * UCAL_HOUR_OF_DAY
  89.  * UCAL_AM_PM + UCAL_HOUR
  90.  * </pre>
  91.  * </blockquote>
  92.  *
  93.  * <p>
  94.  * <strong>Note:</strong> for some non-Gregorian calendars, different
  95.  * fields may be necessary for complete disambiguation. For example, a full
  96.  * specification of the historial Arabic astronomical calendar requires year,
  97.  * month, day-of-month <em>and</em> day-of-week in some cases.
  98.  *
  99.  * <p>
  100.  * <strong>Note:</strong> There are certain possible ambiguities in
  101.  * interpretation of certain singular times, which are resolved in the
  102.  * following ways:
  103.  * <ol>
  104.  *     <li> 24:00:00 "belongs" to the following day. That is,
  105.  *          23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970
  106.  *
  107.  *     <li> Although historically not precise, midnight also belongs to "am",
  108.  *          and noon belongs to "pm", so on the same day,
  109.  *          12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm
  110.  * </ol>
  111.  *
  112.  * <p>
  113.  * The date or time format strings are not part of the definition of a
  114.  * calendar, as those must be modifiable or overridable by the user at
  115.  * runtime. Use {@link UDateFormat}
  116.  * to format dates.
  117.  *
  118.  * <p>
  119.  * <code>Calendar</code> provides an API for field "rolling", where fields
  120.  * can be incremented or decremented, but wrap around. For example, rolling the
  121.  * month up in the date <code>December 12, <b>1996</b></code> results in
  122.  * <code>January 12, <b>1996</b></code>.
  123.  *
  124.  * <p>
  125.  * <code>Calendar</code> also provides a date arithmetic function for
  126.  * adding the specified (signed) amount of time to a particular time field.
  127.  * For example, subtracting 5 days from the date <code>September 12, 1996</code>
  128.  * results in <code>September 7, 1996</code>.
  129.  *
  130.  */
  131. /** A calendar */
  132. typedef void* UCalendar;
  133.  
  134. /** Possible types of UCalendars */
  135. enum UCalendarType {
  136.   /** A traditional calendar for the locale */
  137.   UCAL_TRADITIONAL,
  138.   /** The Gregorian calendar */
  139.   UCAL_GREGORIAN
  140. };
  141. typedef enum UCalendarType UCalendarType;
  142.     
  143. /** Possible fields in a UCalendar */
  144. enum UCalendarDateFields {
  145.   /** Era field */
  146.   UCAL_ERA,
  147.   /** Year field */
  148.   UCAL_YEAR,
  149.   /** Month field */
  150.   UCAL_MONTH,
  151.   /** Week of year field */
  152.   UCAL_WEEK_OF_YEAR,
  153.   /** Week of month field */
  154.   UCAL_WEEK_OF_MONTH,
  155.   /** Date field */
  156.   UCAL_DATE,
  157.   /** Day of year field */
  158.   UCAL_DAY_OF_YEAR,
  159.   /** Day of week field */
  160.   UCAL_DAY_OF_WEEK,
  161.   /** Day of week in month field */
  162.   UCAL_DAY_OF_WEEK_IN_MONTH,
  163.   /** AM/PM field */
  164.   UCAL_AM_PM,
  165.   /** Hour field */
  166.   UCAL_HOUR,
  167.   /** Hour of day field */
  168.   UCAL_HOUR_OF_DAY,
  169.   /** Minute field */
  170.   UCAL_MINUTE,
  171.   /** Second field */
  172.   UCAL_SECOND,
  173.   /** Millisecond field */
  174.   UCAL_MILLISECOND,
  175.   /** Zone offset field */
  176.   UCAL_ZONE_OFFSET,
  177.   /** DST offset field */
  178.   UCAL_DST_OFFSET,
  179.   /** Field count */
  180.   UCAL_FIELD_COUNT
  181. };
  182. typedef enum UCalendarDateFields UCalendarDateFields;
  183.     /**
  184.      * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
  185.      * who create locale resources for the field of first-day-of-week should be aware of
  186.      * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY.
  187.      */
  188. /** Possible days of the week in a UCalendar */
  189. enum UCalendarDaysOfWeek {
  190.   /** Sunday */
  191.   UCAL_SUNDAY = 1,
  192.   /** Monday */
  193.   UCAL_MONDAY,
  194.   /** Tuesday */
  195.   UCAL_TUESDAY,
  196.   /** Wednesday */
  197.   UCAL_WEDNESDAY,
  198.   /** Thursday */
  199.   UCAL_THURSDAY,
  200.   /** Friday */
  201.   UCAL_FRIDAY,
  202.   /** Saturday */
  203.   UCAL_SATURDAY
  204. };
  205. typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
  206.  
  207. /** Possible months in a UCalendar. Note: Calendar month is 0-based.*/
  208. enum UCalendarMonths {
  209.   /** January */
  210.   UCAL_JANUARY,
  211.   /** February */
  212.   UCAL_FEBRUARY,
  213.   /** March */
  214.   UCAL_MARCH,
  215.   /** April */
  216.   UCAL_APRIL,
  217.   /** May */
  218.   UCAL_MAY,
  219.   /** June */
  220.   UCAL_JUNE,
  221.   /** July */
  222.   UCAL_JULY,
  223.   /** August */
  224.   UCAL_AUGUST,
  225.   /** September */
  226.   UCAL_SEPTEMBER,
  227.   /** October */
  228.   UCAL_OCTOBER,
  229.   /** November */
  230.   UCAL_NOVEMBER,
  231.   /** December */
  232.   UCAL_DECEMBER,
  233.   /** Undecimber */
  234.   UCAL_UNDECIMBER
  235. };
  236. typedef enum UCalendarMonths UCalendarMonths;
  237.  
  238. /** Possible AM/PM values in a UCalendar */
  239. enum UCalendarAMPMs {
  240.     /** AM */
  241.   UCAL_AM,
  242.   /** PM */
  243.   UCAL_PM
  244. };
  245. typedef enum UCalendarAMPMs UCalendarAMPMs;
  246.  
  247. /**
  248. * Get an available TimeZone ID.
  249. * A Timezone ID is a string of the form "America/Los Angeles".
  250. * @param rawOffset The desired GMT offset
  251. * @param index The index of the desired TimeZone.
  252. * @param status A pointer to an UErrorCode to receive any errors
  253. * @return The requested TimeZone ID, or 0 if not found
  254. * @see ucal_countAvailableTZIDs
  255. */
  256. U_CAPI const UChar*
  257. ucal_getAvailableTZIDs(        int32_t         rawOffset,
  258.                 int32_t         index,
  259.                 UErrorCode*     status);
  260.  
  261. /**
  262. * Determine how many TimeZones exist with a certain offset.
  263. * This function is most useful as determining the loop ending condition for
  264. * calls to \Ref{ucal_getAvailableTZIDs}.
  265. * @param rawOffset The desired GMT offset.
  266. * @return The number of TimeZones with rawOffset.
  267. * @see ucal_getAvailableTZIDs
  268. */
  269. U_CAPI int32_t
  270. ucal_countAvailableTZIDs(int32_t rawOffset);
  271.  
  272. /**
  273. * Get the current date and time.
  274. * The value returned is represented as milliseconds from the epoch.
  275. * @return The current date and time.
  276. */
  277. U_CAPI UDate 
  278. ucal_getNow(void);
  279.  
  280. /**
  281. * Open a UCalendar.
  282. * A UCalendar may be used to convert a millisecond value to a year, 
  283. * month, and day.
  284. * @param zoneID The desired TimeZone ID.  If 0, use the default time zone.
  285. * @param len The length of zoneID, or -1 if null-terminated.
  286. * @param locale The desired locale
  287. * @param type The type of UCalendar to open.
  288. * @param status A pointer to an UErrorCode to receive any errors
  289. * @return A pointer to a UCalendar, or 0 if an error occurred.
  290. */
  291. U_CAPI UCalendar* 
  292. ucal_open(    const    UChar*          zoneID,
  293.             int32_t        len,
  294.         const    char*           locale,
  295.             UCalendarType     type,
  296.             UErrorCode*    status);
  297.  
  298. /**
  299. * Close a UCalendar.
  300. * Once closed, a UCalendar may no longer be used.
  301. * @param cal The UCalendar to close.
  302. */
  303. U_CAPI void
  304. ucal_close(UCalendar *cal);
  305.  
  306. /**
  307. * Set the TimeZone used by a UCalendar.
  308. * A UCalendar uses a timezone for converting from Greenwich time to local time.
  309. * @param cal The UCalendar to set.
  310. * @param zoneID The desired TimeZone ID.  If 0, use the default time zone.
  311. * @param len The length of zoneID, or -1 if null-terminated.
  312. * @param status A pointer to an UErrorCode to receive any errors.
  313. */
  314. U_CAPI void 
  315. ucal_setTimeZone(        UCalendar*      cal,
  316.             const    UChar*        zoneID,
  317.                 int32_t        len,
  318.                 UErrorCode     *status);
  319.  
  320. /** Possible formats for a UCalendar's display name */
  321. enum UCalendarDisplayNameType {
  322.   /** Standard display name */
  323.   UCAL_STANDARD,
  324.   /** Short standard display name */
  325.   UCAL_SHORT_STANDARD,
  326.   /** Daylight savings display name */
  327.   UCAL_DST,
  328.   /** Short daylight savings display name */
  329.   UCAL_SHORT_DST
  330. };
  331. typedef enum UCalendarDisplayNameType UCalendarDisplayNameType;
  332.  
  333. /**
  334. * Get the display name for a UCalendar's TimeZone.
  335. * A display name is suitable for presentation to a user.
  336. * @param cal The UCalendar to query.
  337. * @param type The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD, 
  338. * UCAL_DST, UCAL_SHORT_DST
  339. * @param locale The desired locale for the display name.
  340. * @param status A pointer to an UErrorCode to receive any errors
  341. * @param result A pointer to a buffer to receive the formatted number.
  342. * @param resultLength The maximum size of result.
  343. * @param resultLengthNeeded If not 0, on output the number of characters actually
  344. * written to result.
  345. * @return The total buffer size needed; if greater than resultLength, the output was truncated.
  346. */
  347. U_CAPI int32_t
  348. ucal_getTimeZoneDisplayName(    const     UCalendar*                 cal,
  349.                     UCalendarDisplayNameType     type,
  350.                 const      char                     *locale,
  351.                     UChar*                  result,
  352.                     int32_t                 resultLength,
  353.                     UErrorCode*             status);
  354.  
  355. /**
  356. * Determine if a UCalendar is currently in daylight savings time.
  357. * Daylight savings time is not used in all parts of the world.
  358. * @param cal The UCalendar to query.
  359. * @param status A pointer to an UErrorCode to receive any errors
  360. * @return TRUE if cal is currently in daylight savings time, FALSE otherwise
  361. */
  362. U_CAPI bool_t 
  363. ucal_inDaylightTime(    const    UCalendar*      cal, 
  364.                 UErrorCode*     status );
  365.  
  366. /** Types of UCalendar attributes */
  367. enum UCalendarAttribute {
  368.     /** Lenient parsing */
  369.   UCAL_LENIENT,
  370.   /** First day of week */
  371.   UCAL_FIRST_DAY_OF_WEEK,
  372.   /** Minimum number of days in first week */
  373.   UCAL_MINIMAL_DAYS_IN_FIRST_WEEK    
  374. };
  375. typedef enum UCalendarAttribute UCalendarAttribute;
  376.  
  377. /** 
  378. * Get a numeric attribute associated with a UCalendar.
  379. * Numeric attributes include the first day of the week, or the minimal numbers
  380. * of days in the first week of the month.
  381. * @param cal The UCalendar to query.
  382. * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK, 
  383. * or UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
  384. * @return The value of attr.
  385. * @see ucal_setAttribute
  386. */
  387. U_CAPI int32_t
  388. ucal_getAttribute(    const    UCalendar*              cal,
  389.                 UCalendarAttribute      attr);
  390.  
  391. /** 
  392. * Set a numeric attribute associated with a UCalendar.
  393. * Numeric attributes include the first day of the week, or the minimal numbers
  394. * of days in the first week of the month.
  395. * @param cal The UCalendar to set.
  396. * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK, 
  397. * or UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
  398. * @param newValue The new value of attr.
  399. * @see ucal_getAttribute
  400. */
  401. U_CAPI void
  402. ucal_setAttribute(      UCalendar*              cal,
  403.             UCalendarAttribute      attr,
  404.             int32_t                 newValue);
  405.  
  406. /**
  407. * Get a locale for which calendars are available.
  408. * A UCalendar in a locale returned by this function will contain the correct
  409. * day and month names for the locale.
  410. * @param index The index of the desired locale.
  411. * @return A locale for which calendars are available, or 0 if none.
  412. * @see ucal_countAvailable
  413. */
  414. U_CAPI const char*
  415. ucal_getAvailable(int32_t index);
  416.  
  417. /**
  418. * Determine how many locales have calendars available.
  419. * This function is most useful as determining the loop ending condition for
  420. * calls to \Ref{ucal_getAvailable}.
  421. * @return The number of locales for which calendars are available.
  422. * @see ucal_getAvailable
  423. */
  424. U_CAPI int32_t
  425. ucal_countAvailable(void);
  426.  
  427. /**
  428. * Get a UCalendar's current time in millis.
  429. * The time is represented as milliseconds from the epoch.
  430. * @param cal The UCalendar to query.
  431. * @param status A pointer to an UErrorCode to receive any errors
  432. * @return The calendar's current time in millis.
  433. * @see ucal_setMillis
  434. * @see ucal_setDate
  435. * @see ucal_setDateTime
  436. */
  437. U_CAPI UDate 
  438. ucal_getMillis(    const    UCalendar*      cal,
  439.             UErrorCode*     status);
  440.  
  441. /**
  442. * Set a UCalendar's current time in millis.
  443. * The time is represented as milliseconds from the epoch.
  444. * @param cal The UCalendar to set.
  445. * @param dateTime The desired date and time.
  446. * @param status A pointer to an UErrorCode to receive any errors
  447. * @see ucal_getMillis
  448. * @see ucal_setDate
  449. * @see ucal_setDateTime
  450. */
  451. U_CAPI void 
  452. ucal_setMillis(        UCalendar*      cal,
  453.             UDate           dateTime,
  454.             UErrorCode*     status );
  455.  
  456. /**
  457. * Set a UCalendar's current date.
  458. * The date is represented as a series of 32-bit integers.
  459. * @param cal The UCalendar to set.
  460. * @param year The desired year.
  461. * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY, 
  462. * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
  463. * @param date The desired day of the month.
  464. * @param status A pointer to an UErrorCode to receive any errors
  465. * @see ucal_getMillis
  466. * @see ucal_setMillis
  467. * @see ucal_setDateTime
  468. */
  469. U_CAPI void 
  470. ucal_setDate(        UCalendar*        cal,
  471.             int32_t            year,
  472.             int32_t            month,
  473.             int32_t            date,
  474.             UErrorCode        *status);
  475.  
  476. /**
  477. * Set a UCalendar's current date.
  478. * The date is represented as a series of 32-bit integers.
  479. * @param cal The UCalendar to set.
  480. * @param year The desired year.
  481. * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY, 
  482. * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
  483. * @param date The desired day of the month.
  484. * @param hour The desired hour of day.
  485. * @param minute The desired minute.
  486. * @param second The desirec second.
  487. * @param status A pointer to an UErrorCode to receive any errors
  488. * @see ucal_getMillis
  489. * @see ucal_setMillis
  490. * @see ucal_setDate
  491. */
  492. U_CAPI void 
  493. ucal_setDateTime(    UCalendar*        cal,
  494.             int32_t            year,
  495.             int32_t            month,
  496.             int32_t            date,
  497.             int32_t            hour,
  498.             int32_t            minute,
  499.             int32_t            second,
  500.             UErrorCode        *status);
  501.  
  502. /**
  503. * Determine if two UCalendars represent the same date.
  504. * Two UCalendars may represent the same date and have different fields
  505. * if they are in different time zones.
  506. * @param cal1 The first of the UCalendars to compare.
  507. * @param cal2 The second of the UCalendars to compare.
  508. * @return TRUE if cal1 and cal2 represent the same date, FALSE otherwise.
  509. */
  510. U_CAPI bool_t 
  511. ucal_equivalentTo(    const UCalendar*      cal1,
  512.             const UCalendar*      cal2);
  513.  
  514. /**
  515. * Add a specified signed amount to a particular field in a UCalendar.
  516. * This can modify more significant fields in the calendar.
  517. * @param cal The UCalendar to which to add.
  518. * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 
  519. * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 
  520. * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 
  521. * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
  522. * @param amount The signed amount to add to field. If the amount causes the value
  523. * to exceed to maximum or minimum values for that field, other fields are modified
  524. * to preserve the magnitude of the change.
  525. * @param status A pointer to an UErrorCode to receive any errors
  526. * @see ucal_roll
  527. */
  528. U_CAPI void 
  529. ucal_add(    UCalendar*            cal,
  530.         UCalendarDateFields        field,
  531.         int32_t                amount,
  532.         UErrorCode*            status);
  533.  
  534. /**
  535. * Add a specified signed amount to a particular field in a UCalendar.
  536. * This will not modify more significant fields in the calendar.
  537. * @param cal The UCalendar to which to add.
  538. * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 
  539. * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 
  540. * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 
  541. * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
  542. * @param amount The signed amount to add to field. If the amount causes the value
  543. * to exceed to maximum or minimum values for that field, the field is pinned to a permissible
  544. * value.
  545. * @param status A pointer to an UErrorCode to receive any errors
  546. * @see ucal_add
  547. */
  548. U_CAPI void 
  549. ucal_roll(        UCalendar*        cal,
  550.             UCalendarDateFields     field,
  551.             int32_t            amount,
  552.             UErrorCode*        status);
  553.  
  554. /**
  555. * Get the current value of a field from a UCalendar.
  556. * All fields are represented as 32-bit integers.
  557. * @param cal The UCalendar to query.
  558. * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 
  559. * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 
  560. * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 
  561. * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
  562. * @param status A pointer to an UErrorCode to receive any errors
  563. * @return The value of the desired field.
  564. * @see ucal_set
  565. * @see ucal_isSet
  566. * @see ucal_clearField
  567. * @see ucal_clear
  568. */
  569. U_CAPI int32_t 
  570. ucal_get(    const    UCalendar*            cal,
  571.             UCalendarDateFields        field,
  572.             UErrorCode*            status );
  573.  
  574. /**
  575. * Set the value of a field in a UCalendar.
  576. * All fields are represented as 32-bit integers.
  577. * @param cal The UCalendar to set.
  578. * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 
  579. * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 
  580. * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 
  581. * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
  582. * @param value The desired value of field.
  583. * @see ucal_get
  584. * @see ucal_isSet
  585. * @see ucal_clearField
  586. * @see ucal_clear
  587. */
  588. U_CAPI void 
  589. ucal_set(    UCalendar*            cal,
  590.         UCalendarDateFields        field,
  591.         int32_t                value);
  592.  
  593. /**
  594. * Determine if a field in a UCalendar is set.
  595. * All fields are represented as 32-bit integers.
  596. * @param cal The UCalendar to query.
  597. * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 
  598. * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 
  599. * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 
  600. * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
  601. * @param return TRUE if field is set, FALSE otherwise.
  602. * @see ucal_get
  603. * @see ucal_set
  604. * @see ucal_clearField
  605. * @see ucal_clear
  606. */
  607. U_CAPI bool_t 
  608. ucal_isSet(    const    UCalendar*        cal,
  609.             UCalendarDateFields    field);
  610.  
  611. /**
  612. * Clear a field in a UCalendar.
  613. * All fields are represented as 32-bit integers.
  614. * @param cal The UCalendar containing the field to clear.
  615. * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 
  616. * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 
  617. * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 
  618. * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
  619. * @see ucal_get
  620. * @see ucal_set
  621. * @see ucal_isSet
  622. * @see ucal_clear
  623. */
  624. U_CAPI void 
  625. ucal_clearField(    UCalendar*        cal,
  626.             UCalendarDateFields     field);
  627.  
  628. /**
  629. * Clear all fields in a UCalendar.
  630. * All fields are represented as 32-bit integers.
  631. * @param cal The UCalendar to clear.
  632. * @see ucal_get
  633. * @see ucal_set
  634. * @see ucal_isSet
  635. * @see ucal_clearField
  636. */
  637. U_CAPI void 
  638. ucal_clear(UCalendar* calendar);
  639.  
  640. /** Possible limit values for a UCalendar */
  641. enum UCalendarLimitType {
  642.   /** Minimum value */
  643.   UCAL_MINIMUM,
  644.   /** Maximum value */
  645.   UCAL_MAXIMUM,
  646.   /** Greatest minimum value */
  647.   UCAL_GREATEST_MINIMUM,
  648.   /** Leaest maximum value */
  649.   UCAL_LEAST_MAXIMUM,
  650.   /** Actual minimum value */
  651.   UCAL_ACTUAL_MINIMUM,
  652.   /** Actual maximum value */
  653.   UCAL_ACTUAL_MAXIMUM
  654. };
  655. typedef enum UCalendarLimitType UCalendarLimitType;
  656.  
  657. /**
  658. * Determine a limit for a field in a UCalendar.
  659. * A limit is a maximum or minimum value for a field.
  660. * @param cal The UCalendar to query.
  661. * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 
  662. * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 
  663. * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 
  664. * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
  665. * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM, 
  666. * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM
  667. * @param status A pointer to an UErrorCode to receive any errors.
  668. * @return The requested value.
  669. */
  670. U_CAPI int32_t 
  671. ucal_getLimit(    const    UCalendar*              cal,
  672.             UCalendarDateFields     field,
  673.             UCalendarLimitType      type,
  674.             UErrorCode        *status);
  675.  
  676. #endif
  677.